From 2acf529b3bef8d88af522c772fb39e3348667ed6 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 10 Aug 2010 21:21:01 -0400 Subject: [PATCH] Beef up the migration guide This includes a first cut at documenting the rendering cleanup changes and the region removal. --- docs/reference/gtk/gtk-docs.sgml | 2 +- docs/reference/gtk/migrating-2to3.xml | 386 +++++++++++++++++++++++++- 2 files changed, 374 insertions(+), 14 deletions(-) diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 42b43a9083..6bd485f74c 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -428,7 +428,7 @@ that is, GUI components such as #GtkButton or #GtkTextView. - + diff --git a/docs/reference/gtk/migrating-2to3.xml b/docs/reference/gtk/migrating-2to3.xml index 8e67bb58ed..1652177cf8 100644 --- a/docs/reference/gtk/migrating-2to3.xml +++ b/docs/reference/gtk/migrating-2to3.xml @@ -6,14 +6,69 @@ Migrating from GTK+ 2.x to GTK+ 3 - There are a number of steps that you can take to prepare your GTK+ 2.x - application for the switch to GTK+ 3. + GTK+ 3 is a major new version of GTK+, which breaks both API and ABI + compared to GTK+ 2.x, which has remained API- and ABI-stable for a + long time. Thankfully, most of the changes are not hard to adapt to + and there are a number of steps that you can take to prepare your + GTK+ 2.x application for the switch to GTK+ 3. After that, there's + a small number of adjustments that you may have to do when you actually + switch your application to build against GTK+ 3.
- Only single includes + Preparation in GTK+ 2.x + + + The steps outlined in the following sections assume that your + application is working with GTK+ 2.22, which is the final stable + release of GTK+ 2.x. It includes all the necessary APIs and tools + to help you port your application to GTK+ 3. If you are still using + an older version of GTK+ 2.x, you should first get your application + to build and work with 2.22. + + +
+ Do not include individual headers + + With GTK+ 2.x it was common to include just the header files for + a few widgets that your application was using, which could lead + to problems with missing definitions, etc. GTK+ 3 tightens the + rules about which header files you are allowed to include directly. + The allowed header files are are + + + gtk/gtk.h + for GTK + + + gtk/gtkunixprint.h + for low-level, UNIX-specific printing functions + + + gdk-pixbuf/gdk-pixbuf.h + for GdkPixbuf + + + gdk/gdk.h + for GDK + + + gdk/gdkx.h + for GDK functions that are X11-specific + + + gdk/gdkkeysyms.h + if you need the GDK keysym definitions + + + (these relative paths are assuming that you are using the include + paths that are specified in the gtk+-2.0.pc file, as returned by + pkg-config --cflags gtk+-2.0.pc.) + - Make sure your program only include the toplevel headers: + To check that your application only includes the allowed headers, + you can use defines to disable inclusion of individual headers, + as follows: make CFLAGS+="-DG_DISABLE_SINGLE_INCLUDES -DGDK_PIXBUF_DISABLE_SINGLE_INCLUDES -DGTK_DISABLE_SINGLE_INCLUDES" @@ -23,8 +78,17 @@
Do not use deprecated symbols - Make sure your program doesn't use any functions that have been - deprecated in GTK+ 2.x: + Over the years, a number of functions, and in some cases, entire + widgets have been deprecated. These deprecations are clearly spelled + out in the API reference, with hints about the recommended replacements. + The API reference also includes an + index of all deprecated + symbols. + + + To verify that your program does not use any deprecated symbols, + you can use defines to remove deprecated symbols from the header files, + as follows: make CFLAGS+="-DG_DISABLE_DEPRECATED -DGDK_PIXBUF_DISABLE_DEPRECATED -DGDK_DISABLE_DEPRECATED -DGTK_DISABLE_DEPRECATED" @@ -35,20 +99,313 @@ Use accessor functions instead direct access GTK+ 3 removes many implementation details and struct members from - its public headers. To ensure that your application does not have problems - with this, you define the preprocessor symbol GSEAL_ENABLE. This will - make the compiler catch all uses of direct access to struct fields so that - you can go through them one by one and replace them with a call to an - accessor function instead. + its public headers. + + + To ensure that your application does not have problems with this, you + define the preprocessor symbol GSEAL_ENABLE. This + will make the compiler catch all uses of direct access to struct fields + so that you can go through them one by one and replace them with a call + to an accessor function instead. make CFLAGS+="-DGSEAL_ENABLE" - Starting with 2.90.4, GTK+'s .pc files turn on GSEAL_ENABLE by default.
- GTK+ Modules + Use cairo for drawing + + In GTK+ 3, the GDK drawing API (which closely mimics the X + drawing API, which is itself modeled after PostScript) has been + removed. All drawing in GTK+ 3 is done via cairo. + + + The #GdkGC and #GdkImage objects, as well as all the functions using + them are gone. This includes the gdk_draw_ family + of functions like gdk_draw_rectangle() and gdk_draw_drawable(). As + #GdkGC is roughly equivalent to #cairo_t and #GdkImage was used for + drawing images to GdkDrawables, which cairo supports automatically, + a transition is usually straightforward. + + + The following examples show a few common drawing idioms used by + applications that have been ported to use cairo and how the code + was replaced. + + + Drawing a GdkPixbuf onto a GdkDrawable + + Drawing a pixbuf onto a drawable used to be done like this: +black_gc, + pixbuf, + 0, 0 + x, y, + gdk_pixbuf_get_width (pixbuf), + gdk_pixbuf_get_height (pixbuf), + GDK_RGB_DITHER_NORMAL, + 0, 0); +]]> + Doing the same thing with cairo: + + Note that very similar code can be used for drawing pixmaps + by using gdk_cairo_set_source_pixmap() instead of + gdk_cairo_set_source_pixbuf(). + + + + Drawing a tiled GdkPixmap to a GdkDrawable + + Tiled pixmaps are often used for drawing backgrounds. + Old code looked something like this: + black_gc; +gdk_gc_set_tile (gc, pixmap); +gdk_gc_set_fill (gc, GDK_TILED); +gdk_gc_set_ts_origin (gc, x_origin, y_origin); +/* use */ +gdk_draw_rectangle (drawable, gc, TRUE, 0, 0, width, height); +/* restore */ +gdk_gc_set_tile (gc, NULL); +gdk_gc_set_fill (gc, GDK_SOLID); +gdk_gc_set_ts_origin (gc, 0, 0); +]]> + The equivalent Cairo code looks like this: + + Again, you can exchange pixbufs and pixmaps by using + gdk_cairo_set_source_pixbuf() instead of + gdk_cairo_set_source_pixmap(). + + + + Drawing a PangoLayout to a clipped area + + Drawing layouts clipped is often used to avoid overdraw or to + allow drawing selections. Code would have looked like this: +text_gc[state]; +gdk_gc_set_clip_rectangle (gc, &area); +/* use */ +gdk_draw_layout (drawable, gc, x, y, layout); +/* restore */ +gdk_gc_set_clip_rectangle (gc, NULL); +]]> + With Cairo, the same effect can be achieved using: +text[state]); +/* draw the text */ +cairo_move_to (cr, x, y); +pango_cairo_show_layout (cr, layout); +cairo_destroy (cr); +]]> + Clipping using cairo_clip() is of course not restricted to text + rendering and can be used everywhere where GC clips were used. + And using gdk_cairo_set_source_color() with style colors should + be used in all the places where a style’s GC was used to achieve + a particular color. + + +
+ what should you be aware of ? + No more stippling + + Stippling is the usage of a bi-level mask, called a #GdkBitmap. + It was often used to achieve a checkerboard effect. You can use + cairo_mask() to achieve this effect. To get a checkerbox mask, + you can use code like this: + + Note that stippling looks very outdated in UIs, and is rarely + used in modern applications. All properties that made use of + stippling have been removed from GTK+ 3. Most prominently, + stippling is absent from text rendering, in particular #GtkTextTag. + + + Using the the target drawable also as source or mask + + The gdk_draw_drawable() function allowed using the same drawable + as source and target. This was often used to achieve a scrolling + effect. Cairo does not allow this yet. You can however use + cairo_push_group() to get a different intermediate target that + you can copy to. So you can replace this code: + + By using this code: + + The cairo developers plan to add self-copies in the future to allow + exactly this effect, so you might want to keep up on cairo + development to be able to change your code. + + + Using pango_cairo_show_layout() instead of gdk_draw_layout_with_colors() + + GDK provided a way to ignore the color attributes of text and use + a hardcoded text color with the gdk_draw_layout_with_colors() + function. This is often used to draw text shadows or selections. + Pango’s cairo support does not yet provide this functionality. If + you use Pango layouts that change colors, the easiest way to achieve + a similar effect is using pango_cairo_layout_path() and cairo_fill() + instead of gdk_draw_layout_with_colors(). Note that this results in + a slightly uglier-looking text, as subpixel anti-aliasing is not + supported. + + +
+
+
+ +
+ Changes that need to be done at the time of the switch + + + This section outlines porting tasks that you need to tackle when + you get to the point that you actually build your application against + GTK+ 3. Making it possible to prepare for these in GTK+ 2.22 would + have been either impossible or impractical. + + +
+ Replace GdkRegion by cairo_region_t + + + Starting with version 1.10, cairo provides a region API that is + equivalent to the GDK region API (which was itself copied from + the X server). Therefore, the region API has been removed in GTK+ 3. + + + Porting your application to the cairo region API should be a straight + find-and-replace task. Please refer to the following table: + + + + GDKcairo + + + #GdkRegion#cairo_region_t + #GdkRectangle#cairo_rectangle_int_t + gdk_rectangle_intersect()this function is still there + gdk_rectangle_union()this function is still there + gdk_region_new()cairo_region_create() + gdk_region_copy()cairo_region_copy() + gdk_region_destroy()cairo_region_destroy() + gdk_region_rectangle()cairo_region_create_rectangle() + gdk_region_get_clipbox()cairo_region_get_extents() + gdk_region_get_rectangles()cairo_region_num_rectangles() and + cairo_region_get_rectangle() + gdk_region_empty()cairo_region_is_empty() + gdk_region_equal()cairo_region_equal() + gdk_region_point_in()cairo_region_contains_point() + gdk_region_rect_in()cairo_region_contains_rectangle() + gdk_region_offset()cairo_region_translate() + gdk_region_union_with_rect()cairo_region_union_rectangle() + gdk_region_intersect()cairo_region_intersect() + gdk_region_union()cairo_region_union() + gdk_region_subtract()cairo_region_subtract() + gdk_region_xor()cairo_region_xor() + gdk_region_shrink()no replacement + gdk_region_polygon()no replacement, use cairo paths instead + + +
+ +
+ +
+ Prevent mixed linkage + + Linking against GTK+ 2.x and GTK+ 3 in the same process is problematic + and can lead to hard-to-diagnose crashes. The gtk_init() function in + both GTK+ 2.22 and in GTK+ 3 tries to detect this situation and abort + with a diagnostic message, but this check is not 100% reliable (e.g. if + the problematic linking happens only in loadable modules). + + + Direct linking of your application against both versions of GTK+ is + easy to avoid; the problem gets harder when your application is using + libraries that are themselves linked against some version of GTK+. + In that case, you have to verify that you are using a version of the + library that is linked against GTK+ 3. + + + If you are using packages provided by a distributor, it is likely that + parallel installable versions of the library exist for GTK+ 2.x and + GTK+ 3, e.g for vte, check for vte3; for webkitgtk look for webkitgtk3, + and so on. + +
+ +
+ Install GTK+ modules in the right place Some software packages install loadable GTK+ modules such as theme engines, gdk-pixbuf loaders or input methods. Since GTK+ 3 is parallel-installable @@ -78,4 +435,7 @@ unhappiness and must be avoided.
+ +
+ -- 2.30.2